//=========================================================================
// Copyright (C) 2025 The C++ Component Model(COMO) Open Source Project
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//=========================================================================

#ifndef __DataFrames_H__
#define __DataFrames_H__

#include <stdint.h>

#ifdef __cplusplus
extern "C"
{
#endif

/**
 * @brief 通信数据帧结构定义
 *
 * 数据流格式：
 * ┌──────────────────────────────┐
 * │ 有效数据长度（2 字节，大端） │
 * │ CRC 校验（2 字节，大端）     │
 * │ 包流向（1 字节）             │
 * │ 设备 ID（1 字节）            │
 * │ 主备机标识（1 字节）         │
 * │ 数据类型（1 字节）           │
 * │ 数据包数量（1 字节）         │
 * │ 当前小包序号（1 字节）       │
 * │ 发送序号（1 字节）           │
 * │ 用户数据（n 字节）           │
 * └──────────────────────────────┘
 *
 * 注意事项：
 * - 有效数据长度与 CRC 均采用 **高字节在前（big-endian）**。
 * - 用户数据长度不超过 2000 字节，否则应报警并停止发送。
 * - 每个字段均为对齐到字节边界。
 */

#pragma pack(push, 1)  // 禁止结构体对齐填充

struct DataFrame_TKY_1
{
    /**
     * @brief 有效数据长度（高字节在前）
     * 表示从“包流向”开始到末尾的总字节数。
     */
    uint16_t valid_length;

    /**
     * @brief 数据区 CRC 校验（高字节在前）
     * 校验范围为从“包流向”开始至用户数据结尾。
     */
    uint16_t crc;

    /**
     * @brief 包流向
     * 0x4D：MMI -> 逻辑主机
     * 0x49：逻辑主机 -> MMI / MT
     */
    uint8_t direction;

    /**
     * @brief 设备 ID
     * - MMI 发送时：1~4 表示 MMI-A~D
     * - 逻辑主机发送时：1 表示 I 系，2 表示 II 系
     */
    uint8_t device_id;

    /**
     * @brief 主备机标识
     * - MMI 发送：1=主控，2=备用
     * - 逻辑主机发送：
     *   - 0xFD 主控
     *   - 0xF0 备用
     *   - 0x0F 联机
     *   - 0x00 离线
     */
    uint8_t master_slave_flag;

    union {
        uint32_t id_in_Fscp;
        struct {
            /**
             * @brief 数据类型
             * 参见协议文档第 5 章的各数据包定义。
             */
            uint8_t data_type;

            /**
             * @brief 当前数据类型对应的数据包数量（预留）
             * 目前固定填 1，取值范围 1~n。
             */
            uint8_t packet_count;

            /**
             * @brief 当前小包序号（预留）
             * 目前固定填 1，取值范围 1~n。
             */
            uint8_t subpacket_index;

            /**
             * @brief 发送序号
             * - 上电开机第一包：255
             * - 之后循环：0~254
             * 每种数据类型单独计数，用于丢包检测。
             */
            uint8_t send_seq;
        };
    };

    /**
     * @brief 用户数据区
     * 长度不超过 2000 字节。
     * 若超过该长度，应报警并停发数据。
     */
    uint8_t user_data[2000];
};

#pragma pack(pop)

#ifdef __cplusplus
}
#endif

#endif // __DataFrames_H__
